Online Technical Writing:
Book Design

Note: Currently, all I can provide is the following notes on this topic. As soon as possible, I'll develop this in a full chapter. In the meantime, if you have any questions on this topic, contact me at hcexres@io.com. -- David A. McMurrey

In this chapter, book design means the content, style, format, design, and sequence of the various typical components of a book. "Components" here refers to actual sections or pages of a book such as the edition notice, the preface, the index, or the front or back cover. In the page-design chapter, the term element refers to things that can occur multiple times practically anywhere in a book, such as headers, footers, tables, illustrations, lists, notices, highlighting, and so on.

The following provides an overview of the typical components of a printed technical book and the typical content, format, style, and sequence of those components. Certainly, no single user guide, technical reference manual, quick-reference document, or other such document would actually have all of these components designed and sequenced in precisely the way you are about to read. Instead, this review will give an overview of the possibilities ù let's say the range of possibilities.

These book components include:

• Front and back covers
• Title page
• Edition notice
• Disclaimers
• Trademarks
• Warranties
• Safety notices
• Communication statements
• Table of contents
• List of figures
• Preface
• Body chapters
• Appendixes
• Glossary
• Index
• Reader-response form

Before you begin reading the following, grab a number of hardware and software books so that you can compare their content, style. format, and sequencing to what is discussed here.

Product documents for paying customers usually have nicely designed front covers even if, on the inside, the book is bargain basement in terms of its quality. On the front cover, you will typically see:

• Company name
• Product name
• Product platform or operating system
• Product version and release numbers
• Book title
• Company or product logos
• Trademark symbols
• Artwork
• Book order number
• Company or product slogan

It can be challenging to figure out a good format for the company name, product name, and book title. Sometimes, these can amount to a whole paragraph of text! Companies are quite divided on whether to indicate version and release numbers on front covers ù some do; so don't. Almost always, however, you'll the platform indicated ù whether the product is for the Macintosh, the PC, UNIX, and so on.

The title page is typically a duplicate of the front cover, but with certain elements omitted. Typically omitted are the artwork, company or product logos, and slogans. Some technical publications are omitting the title page althogether because of this seemingly needless duplication. (And in a print run of 20,000 copies, a single page means a lot!)

The edition notice is typically the first instance of regular text in a technical publication, although it is typically in smaller type. It occurs on the backside of the title page. If the tecghnical publisher is taking the lean-and-mean approach and eliminating the title page, the edition notice will appear on the backside of the front cover.

No one likes to read fine print, but take a look at the statements typically included in an edition notice:

• Date of publicationùIncluded not only is the year but sometimes even the month that the book was published.

• Edition numberùwhether the book is a first, second, or third edition.

• Product applicabilityùThe edition notice typically indicates which platform, version, and release number of the product the book applies to.

• Full title of the bookùshown in italics.

• DisclaimersùShockingly, product manufacturers will make statements to the effect that they do not guarantee the book is technically correct, complete, or free from writing problems or that the product is free from minor flaws or that it meets the needs of the customer. You'll be able to find additional diclaimers beyond these as well.

• Copyright symbol and statementùYou'll see the circle-C copyright symbol and some statement warning readers not to copy the book without permission.

• Copyright permissionsùThe high-tech world often moves so rapidly that instead of creating their own versions of a product component and its corresponding documentation, companies will simply buy the code or design and the rights to reprint the documentation as well. This usually entails copyright acknowledgement in the edition notice (although if a lot of borrowing has happened, publishers must get creative about where to put all these acknowledgements).

• Reader responsesùSometimes, the edition notice will include some encouragement to customers to contact the company about product or documentation concerns. Instructions on how to contact the company are sometimes included in the edition notice. Included also is often a rather unfriendly statement that any customer communications become the property of the company.

• TrademarksùSome technical publications list known trademarks in the edition notice. This includes both the company's own trademarks and the trademarks of other companies referenced in the book. With the explosion of new products in the high-tech world, and thus the explosion of trademarks, some publications essentially throw up their hands and insert a simple statement that any references to trademarked product names are owned by their respective companies.

See the section on edition notices, where disclaimers are usually tucked away. If a product or its publication needs a whole separate page for its disclaimers, I'm not buying it!

Although many companies do list their own and other companies trademarks in the edition notice, some prefer to list them on a separate page, just after the edition notice. These placement decisions are almost strictly the provice of company attorneys; as writer, you have to comply no matter how bad the the decision is in tems of book design or writing style. Remember, you list only those trademarked product names that occur in that particular book.

You'll notice that some publications go to extreme measures with trademarks: they'll asterisk or footnote the first, or even every occurrence of a trademarked product name. But again, these are directives of company attorneys unto which technical writers must resign themselves, however sadly.

More legal stuff. These are the "guarantees" that the company will support concerning its product. Sometimes these are published in the front matter of the book; but, more appropriately from a book-design standpoint, they are printed on a separate card and inserted in the shrinkwrap of the book or the product. Again, as with edition notices, this is text you simply bring in as "boilerplate" and position in the right place within the book.

However, you should be aware that companies sometimes maintain multiple versions of edition notices, safety notices, warranties, communication statements and other such. As a writer, you must make sure that you are using the right version (and, in finding out which is correct, you'll have a chance to get out and meet lots of new people in the company!). And whatever you do, don't change the text of these boilerplate items, however horribly they are written. Changes typically must be approved by company attorneys (who typically do so begrudgingly and only after many efforts on your part and after much time has passed).

Hardware products typically have a section of safety notices at the front of their books. These may occur as a subsection of the preface, for example, or a separate section in their own right. These sections typically bring together all of the danger, warning, and caution notices that occur throughout the book and arrange them in some sort of logical way. But even with this up-front alert, hardware books still place the individual notices at the points where they apply. (For more information, see special notices.)

Hardware books also require communications statements as stipulated by the governments of the countries to which these products are shipped. In the U.S., the FCC requires certain communications statements depending on the "class" of the hardware product. As a writer, you must careful to use the right communication statement for the product you are documenting -- and not to edit the statement in any way (holy legal words!).

The table of contents usually contains at least a second-level of detail (the head 1s in the actual text) so that readers can find what they need more precisely. Writers, editors, and book designers typically argue about the sequencing of the TOC. In terms of usability, it's much better to have the TOC as close to the front of the book as possible, if not the very first of the book. In terms of legalities, however, people worry that all those communication statements, warranties, copyrights, trademarks, and safety notices should come first. In those places where usability wins out, the books use every tactic they can to get this legalistic material out of the front matter: warranties are put on separate cards and shrink-wrapped with the book or product; warranties, communication statements, trademarks and other such may be dumped in appendixes.

Technical manuals for ordinary users typically don't have lists of figures. In fact, the figures themselves typically do not have full-blown figure titles. But this isn't to say that a list of figures has no place in technical manuals. It all depends on the reader and the reader's needs -- and the content of the book as well. If the book contains tables, illustrations, charts, graphs, and other such that readers will want to find directly, the list is order.

The function of the preface is to get readers ready to read the book. It does so by characterizing the content and purpose of the book, identifying or even briefly describing the product the book supports, explaining the type of reader for whom the book is meant, outlining the main contents of the book, showing any special conventions or terminology used in the book, providing support and marketing numbers, and other such. In traditional book publishing, the preface comes before the table of contents; but as discussed previously in the TOC section, technical publishing people want the TOC to come earlier in the book for usability reasons.

Oh yes, and there is actual text in these books -- it isn't all front matter! Little else to say here other than most technical books have chapters or sections, and, in some cases, parts. See the chapter on page design for format, style, and design issues for elements such as headers, footers, headings, lists, notices, tables, graphics, cross-references, and highlighting

As you know, appendixes are for material that just doesn't seem to fit in the main part of a book but can't be left out of the book either. Appendixes are often the place for big unwieldy tables. Some technical publications have things like warranties in the appendixes. In terms of format, an appendix is just like a chapter -- except that it is named "Appendix A" or some such, and the headers and footers match that different numbering and naming convention.

Some technical publications include a section of specialized terms and their definitions. Notice that most glossaries use a two-column layout. Typically the term and its definition make up a separate paragraph, with the term lowercase (unless it is a proper name) and in bold, followed by a period, then the definition in regular roman. Notice too that definitions are typically not complete sentences. Good glossary definitions should use the formal-sentence definition technique as described in the definition chapter of this online text. Multiple definitions are typically identified by arabic numbers in parentheses. Glossary paragraphs also contain See references to preferred terms and See also references to related terms.

Indexes are also typically two-column and also contain See references to preferred terms and See also references to related terms. See the chapter on indexing for processes and guidelines for creating good indexes.

Some technical publications contain a mechanism to enable readers to send in comments, questions, and evaluation of the book. Of course, it turns out that these forms more often elicit complaints about faulty function in the product that the book documents. With the rise of the Internet, these forms have gone online, and books merely point to their location online.

Note: This concludes the discussion of print-book components. To complete this overview of the design of printed books, see the chapter on page design, which covers elements such as headers and footers, headings, lists, special notices, tables, graphics, highlighting, cross-references, and more.

Return to the table of contents for the Online Technical Writing Course Guide (the online textbook for online technical communication courses at Austin Community College and other institutions worldwide).

This information is provided and maintained by David A. McMurrey. For information on use, customization, or copies, e-mail hcexres@io.com.